package org.xml.sax;


/**
 * SAX解析方法回调的所有方法的总接口：
 *
 * 在SAX解析器中，可以调用@link org.xml.sax.XMLReader#setContentHandler}方法，
 * 来为SAX解析器绑定该接口的实现，然后解析器就可以使用这个实现类来捕捉文档开始、
 * 文档结束、属性开始、属性结束。。事件
 *
 * 这个接口的事件顺序很重要，因为它是文档布局顺序的映射
 *
 * 注意:在java.net.*包下还有一个类也叫ContentHandler，别引用错了
 *

 * @see org.xml.sax.XMLReader
 * @see org.xml.sax.DTDHandler
 * @see org.xml.sax.ErrorHandler
 */
public interface ContentHandler
{

    /**
     * 设置定位器来查找SAX文档时间的原位置
     *
     * 强烈建议SAX解析器（尽管不是绝对必需的）提供一个定位器：并且它必须在调用ContentHandler任何接口之前设置给应用程序
     *
     * 定位器允许应用程序确定任何文档相关事件的结束位置,
     * 通常，应用程序将使用此信息报告自己的错误（例如与应用程序业务规则不匹配的字符内容）。
     *定位器返回的信息可能不足以用于搜索引擎。
     *
     * 请注意，只有在调用SAX事件回调期间，定位器才会返回正确的信息，
     * 在{@link #startDocument startDocument} 返回之后和{@link #endDocument endDocument} 之前调用，
     *应用程序不应该尝试在任何其他时间使用它
     *
     * @param locator 一个可以返回任何SAX文档事件的位置的对象
     * @see org.xml.sax.Locator
     */
    public void setDocumentLocator (Locator locator);


    /**
     * 文档开始通知
     *
     * SAX解析器会在调用任何其它事件之前（除了{@link #setDocumentLocator setDocumentLocator}事件）调用这个方法，并且只会调用一次
     *
     * @throws org.xml.sax.SAXException any SAX exception, possibly wrapping another exception
     * @see #endDocument
     */
    public void startDocument ()
    throws SAXException;


    /**
     * 文档结束通知
     *
     *此方法的文档与 {@link org.xml.sax.ErrorHandler#fatalError}的文档之间存在明显的矛盾
     * ：在未来的主要版本中解决这个歧义之前，当分析器报告了一个致命的Error（）或抛出异常时，
     * 客户端应该不会假定是否将调用结束的Document（）。
     *
     * SAX解析器只会调用这个方法一次，它将是解析过程中调用的最后一个方法。
     *解析器不应该调用这个方法，直到它已经放弃解析（因为不可恢复的错误）或者到达了输入的结尾。
     *
     * @throws org.xml.sax.SAXException any SAX exception, possibly wrapping another exception
     * @see #startDocument
     */
    public void endDocument()
    throws SAXException;


    /**
     * 开始前缀URI名称空间映射
     *
     * 来自此事件的信息对于正常的命名空间处理不是必需的
     *当http://xml.org/sax/features/namespaces的feature为 true（默认这）时，
     * SAX XML读取器将自动替换元素和属性名称的前缀。
     *
     * 但是，有些情况下，应用程序需要在字符数据或属性值中使用前缀，而不能安全地自动扩展;
     * 如果需要，开始/结束前缀映射事件将信息提供给应用程序以在这些上下文中自行扩展前缀。
     *
     * 请注意，开始/结束前缀映射事件不能保证相对于彼此正确嵌套：
     * 所有startPrefixMapping事件都会在相应的{@link #startElement startElement} 事件之前立即发生，
     * 并且所有{@link #endPrefixMapping endPrefixMapping} 事件将立即发生在相应的{@link #endElement endElement}事件之后，
     * 但他们的顺序是不能保证的。
     *
     * 不应该有“xml”前缀的开始/结束前缀映射事件，因为它是预先声明和不可变的。
     * @param prefix 命名空间前缀；如果没有前缀，就用一个空字符串表示默认元素名称空间
     * @param uri 前缀映射到的名称空间URI
     * @throws org.xml.sax.SAXException 客户端可能在处理期间抛出异常
     * @see #endPrefixMapping
     * @see #startElement
     */
    public void startPrefixMapping (String prefix, String uri)
    throws SAXException;


    /**
     * 结束前缀 - URI映射,可以阅读{@link #startPrefixMapping startPrefixMapping} 获取更多详细信息。
     *这些事件总是在相应的 事件之后立即发生，
     * 这些事件总是在相应的{@link #endElement endElement}事件之后立即发生，但是不保证 {@link #endPrefixMapping endPrefixMapping} 事件的顺序。
     *
     * @param prefix 被映射的前缀。 这是默认映射作用域结束时的空字符串。
     * @throws org.xml.sax.SAXException the client may throw  an exception during processing
     * @see #startPrefixMapping
     * @see #endElement
     */
    public void endPrefixMapping (String prefix)
    throws SAXException;


    /**
     * 接收元素开始的通知。
     *
     * 解析器将在XML文档的每个元素的开始处调用此方法; 每个开始元素事件（即使元素为空）都会有对应的{@link #endElement endElement}事件。
     *元素的所有内容将按照顺序在相应的End Element事件之前进行报告。
     *
     *
     * 此事件允许每个元素最多三个名称组件
     * 1.the Namespace URI
     * 2.the local name;
     * 3.合格的（前缀）名称

     *根据http：xml.org/sax/features/namespaces和http：xml.org/sax/features/namespace-prefixes属性的值，可以提供任何或所有这些属性:
     * 1.名称空间URI和本地名称在namespaces属性为true（默认值）时是必需的;当namespaces属性是 false时是可选的（如果指定了一个，则两者都必须是）;
     *2.当namespace-prefixes属性为true时，限定的名称是必需的，而当namespace-prefixes属性为false时是可选的（默认）
     *
     * 请注意，提供的属性列表将只包含具有显式值（指定或默认值）的属性：＃IMPLIED属性将被省略。
     * 仅当http：xml.org/sax/features/namespace-prefixes属性为true（默认为false，并且对真实值的支持为可选）时，
     * 属性列表将包含用于名称空间声明（xmlns属性）的属性。
     *
     *像{@link #characters characters（）}一样，属性值可能具有需要多个char值的字符
     * @param uri ：名称空间URI或空字符串，如果元素没有名称空间URI或名称空间处理未执行
     * @param localName ：本地名称（不带前缀），或者在命名空间处理未执行的情况下为空字符串
     * @param qName ：限定名称（带前缀），或空字符串（如果限定名称不可用）
     * @param atts 附加到元素的属性。 如果没有属性，它应该是一个空的属性对象。 开始元素返回后，此对象的值是未定义的
     * @throws org.xml.sax.SAXException any SAX exception, possibly wrapping another exception
     * @see #endElement
     * @see org.xml.sax.Attributes
     * @see org.xml.sax.helpers.AttributesImpl
     */
    public void startElement (String uri, String localName, String qName, Attributes atts)
    throws SAXException;


    /**
     * 接收元素结束的通知。
     *
     * SAX解析器将在XML文档中的每个元素的末尾调用此方法; 每个结束Element事件都会有一个对应的{@link #startElement startElement}事件（即使元素为空）
     *
     *
     * @param uri :名称空间URI，如果元素没有名称空间URI或名称空间处理未执行怎为空字符串
     * @param localName ：本地名称（不带前缀），或者在命名空间处理未执行的情况下为空字符串
     * @param qName ：合格的XML名称（带前缀），或空字符串（如果限定名称不可用）
     * @throws org.xml.sax.SAXException any SAX exception, possibly wrapping another exception
     */
    public void endElement (String uri, String localName,
                String qName)
    throws SAXException;


    /**
     * 接收字符数据的通知。
     *
     * 解析器将调用这个方法来报告每个字符数据块;
     * SAX解析器可能会将所有连续的字符数据返回到一个块中，或者可能会将其分割成多个块;
     * 然而，任何单个事件中的所有角色必须来自同一个外部实体，以便定位器提供有用的信息。
     *应用程序不能尝试从指定范围之外的数组读取数据.
     *单个字符可能包含多个Java char值;
     * 因为字符不能用十六位表示，所有有两种重要的情况：
     * 第一种情况下，字符用一个 <em>Surrogate Pair</em>表示，使用两个特殊的Unicode值，这些字符在所谓的码点上方U + FFFF。
     * 第二种情况涉及复合字符，如与一个或多个重音字符组合的基本字符
     *
     * 你的代码不应该假定使用 <code>char</code>-at-a-time  idioms的算法在某些情况下会在字符上工作，他们会分割字符。
     * 这在任何XML允许任意字符，处理指令数据和注释的地方以及从这个方法报告的数据中都是相关的。
     * 每当Java代码操纵国际化文本时，这也是相关的。 这个问题不是唯一的XML。
     *
     * 请注意，一些解析器将使用{@link #ignorableWhitespace ignorableWhitespace} 方法而不是这个方法（必须 验证解析器>）来报告元素内容中的空白。
     *
     * @param ch 来自XML文档的字符
     * @param start 数组中的开始位置
     * @param length 从数组中读取的字符数
     * @throws org.xml.sax.SAXException any SAX exception, possibly wrapping another exception
     * @see #ignorableWhitespace
     * @see org.xml.sax.Locator
     */
    public void characters (char ch[], int start, int length)
    throws SAXException;


    /**
     * 接收元素内容中可忽略空白的通知。
     *
     * 验证解析器必须使用此方法报告元素内容中的每个空白块（请参阅W3C XML 1.0推荐的第2.10节）：
     * 如果非验证解析器能够解析和使用内容模型，则也可以使用此方法.
     *SAX解析器可以将单个块中的所有连续的空白字符返回，或者可以将它们分成几个块;
     * 然而，任何单个事件中的所有角色都必须来自同一个外部实体，以便定位器提供有用的信息。
     * 应用程序不能尝试从指定范围之外的数组读取数据
     *
     * @param ch 来自XML文档的字符
     * @param start 数组中的开始位置
     * @param length 从数组中读取的字符数
     * @throws org.xml.sax.SAXException any SAX exception, possibly wrapping another exception
     * @see #characters
     */
    public void ignorableWhitespace (char ch[], int start, int length)
    throws SAXException;


    /**
     * 接收处理指令的通知
     *
     * 解析器将为找到的每个处理指令调用一次该方法：
     * 请注意，处理指令可能发生在主文档元素之前或之后。
     * SAX解析器不得使用此方法报告XML声明（XML 1.0，第2.8节）或文本声明（XML 1.0，第4.3.1节）。
     * 像{@link #characters characters（）}一样，处理指令数据可能具有需要多个 char 值的字符。
     *
     * @param target 处理指令的目标
     * @param data 处理指令数据，如果没有提供，则返回null。 数据不包含任何将其从目标中分离出来的空格
     * @throws org.xml.sax.SAXException any SAX exception, possibly wrapping another exception
     */
    public void processingInstruction (String target, String data)
    throws SAXException;


    /**
     * 接收跳过的实体的通知.
     *
     * 这不是在标记结构（如元素开始标记或标记声明）内的实体引用。
     * (XML建议要求报告跳过的外部实体。 SAX还报告内部实体扩展/非扩展，除了在标记结构内。)
     *
     * 解析器将在每次跳过实体时调用此方法。
     * 未验证的处理器可能会在实体没有看到声明时跳过实体（例如，因为该实体是在外部DTD子集中声明的）。
     *
     * 根据 http：xml.org/sax/features/external-general-entities 和http://xml.org/sax/features/external-parameter-entities的值，
     * 所有处理器可以跳过外部实体。
     *
     * @param name 被跳过的实体的名称。 如果它是一个参数实体，名称将以'％'开始，如果它是外部DTD子集，它将是字符串“[dtd]”
     * @throws org.xml.sax.SAXException any SAX exception, possibly wrapping another exception
     */
    public void skippedEntity (String name)
    throws SAXException;
}
